home *** CD-ROM | disk | FTP | other *** search
/ Shareware Super Platinum 8 / Shareware Super Platinum 8.iso / mac / PROGTOOL / PREQLB.ZIP;1 / PREQLB.DOC next >
Encoding:
Text File  |  1992-11-03  |  12.8 KB  |  279 lines
  1.                                   PreQLB 2.2
  2.                  Placed in the Public Domain by MicroHelp Inc.
  3.  
  4. Licensing:
  5.      This program was created by MicroHelp Inc. and was originally
  6.      released in our QB-Pro Volume 8.  It is now being placed into the
  7.      Public Domain to assist you in creating your quick libraries.
  8.      This program can be freely distributed without restriction.
  9.  
  10.      The PreQLB.zip file should contain the current executable file an
  11.      this PREQLB.DOC file.  If you discover any problems with this program
  12.      we definitely want to know about them; however, only registered
  13.      users of MicroHelp products can receive tech support on this program.
  14.  
  15.      If you want further information on our line of BASIC add-in libraries
  16.      and other products, please call us at 1-800-922-3383 or in GA at
  17.      (404) 516-0898.  If you discover a problem with PreQLB, you can write
  18.      to us at 4359 Shallowford Industrial Parkway  Marietta, GA  30066.
  19.  
  20.  
  21. Creating Quick Libraries with PREQLB
  22.  
  23.        PREQLB.EXE is used to automatically build a Quick
  24.      library containing all the "external" routines needed by a
  25.      specific program.
  26.  
  27.        PREQLB parses the specified BASIC source code file(s),
  28.      checking for statements that identify the names of external
  29.      routines used in your program. The external references are
  30.      placed into a special object module, having a ".BQL"
  31.      extension.
  32.  
  33.        All of the externals that are required by your program are
  34.      extracted from a list of specified .LIB files to create the
  35.      Quick library. In addition, you can pass to it the names of
  36.      object modules that should be included in the QLB, using the
  37.      #TrailingObject command described below.
  38.  
  39.        PREQLB can be operated from the command line or via dialog
  40.      mode.
  41.  
  42. PREQLB and Command Line Mode
  43.  
  44.      The syntax for command line mode is:
  45.  
  46.                       PREQLB [?] [Filename] [/L] [/Q]
  47.  
  48.        Passing the "?" will display a help screen that gives the
  49.      proper syntax and a brief usage summary.
  50.  
  51.        "Filename" is the name of your BASIC source file. It must
  52.      be in "text" format, as opposed to "fast-load" format. You
  53.      may omit the extension (.BAS) if your program has that
  54.      extension, or if there is a ".MAK" file associated with
  55.      "Filename".
  56.  
  57.      PREQLB looks for files in the following order:
  58.  
  59. \    Filename.MAK - If found, PREQLB will process every
  60.      module listed in the file, including the main program.
  61.                               
  62. \    If a .MAK file is not found, PREQLB looks for
  63.      Filename.BAS. If your file has an extension other than .MAK
  64.      or .BAS, you must pass the complete file name on the command
  65.      line, including the extension.
  66.                               
  67. \    Additionally, PREQLB will look for a Filename.CFG file.
  68.      This configuration file is created when you use Dialog Mode
  69.      (explained under PREQLB and Dialog Mode on page 3) and
  70.      contains the names of the source file (or .MAK file), the
  71.      Quick library support library, the Quick library name, and
  72.      up to twenty additional LINK libraries, along with their
  73.      respective paths.
  74.  
  75.      While parsing the file(s), PREQLB looks for three special
  76.      pre-processing commands embedded in a REMark, just like
  77.      metacommands. Here's the syntax for the commands, shown in
  78.      example form:
  79.  
  80.      '#Libraries: 'C:\PDS\LIB\MUSCLE'
  81.      '#SupportLib: 'C:\PDS\LIB\QBXQLB'          'for PDS
  82.      '#TrailingObject: 'C:\PDS\OBJ\MHSUPFR'
  83.  
  84.      CAUTION: The apostrophes (') surrounding file names are
  85.      required.
  86.  
  87.      '#Libraries
  88.  
  89.        The #Libraries command refers to LINK libraries (.LIB file
  90.      extension), that contain the external routines referenced in
  91.      your program.
  92.  
  93.        You may specify up to 20 #Libraries in your source files.
  94.      Those in excess of 20 are ignored.
  95.  
  96.      '#SupportLib
  97.  
  98.        The #SupportLib command refers to the Quick library
  99.      support library. IMPORTANT: See page 2 of the on-line help screens
  100.      for the name to use with your compiler.
  101.  
  102.        If there is more than one #SupportLib statement, only the
  103.      last one is used.
  104.  
  105.      '#TrailingObject
  106.  
  107.        The #TrailingObject command allows you to pass the name of
  108.      any object modules that are to be unconditionally included
  109.      in your Quick library. You can use this command to include
  110.      customized object modules for individual programs, without
  111.      having to remove the object module with the same name from
  112.      your LINK library.
  113.  
  114.        You may specify up to 20 #TrailingObject modules in your
  115.      source files. Those in excess of 20 are ignored.
  116.  
  117. Switches
  118.  
  119.        The /L switch causes PREQLB to create an ASCII text file
  120.      containing the names of all the external routines in your
  121.      program. This list file will have the same name as
  122.      "Filename" (your program), with an extension of ".LST".
  123.  
  124.        The /Q switch instructs PREQLB to process $INCLUDE files
  125.      only once. If your program has multiple modules, and the
  126.      same $INCLUDE file is specified in more than one of the
  127.      modules, the /Q switch tells PREQLB to search for externals
  128.      in this $INCLUDE file only the first time that it is
  129.      processed. If you receive an "Unresolved External" error
  130.      message from the linker when building the .QLB, try running
  131.      PREQLB without the /Q switch.
  132.  
  133. PREQLB and Dialog Mode
  134.  
  135.        If you run PREQLB with no command line information, PREQLB
  136.      will prompt you for the information it needs to build a
  137.      Quick library for you.
  138.  
  139.        The only fields that must be filled in are the source file
  140.      name and the support library name. All other fields are
  141.      optional.
  142.  
  143.        New with version 2.0 is the dialog box interface. To change
  144.      fields use the TAB key to move "forward", Shift-TAB to move
  145.      "backwards" or ALT-[highlighted letter] to jump to a specific
  146.      field.  The "Build QLB" command button is highlighted by default,
  147.      and pressing the enter key at any time will cause the Quick Library
  148.      to be built. For Help, you can press ALT-H or click on the Help
  149.      command button.  Pressing the ESCape key or clicking on the Cancel
  150.      command button will exit PreQLB.
  151.                                      
  152.        You can enter the name of the source or .MAK file,
  153.      the QLB support library, up to five link libraries, and the
  154.      output QLB name.  If you do not enter a name for the Quick
  155.      Library, it will named the same as your source/make file with
  156.      the .QLB extension.
  157.  
  158.        The source file is the name of your source or .MAK file,
  159.      including the path, if desired. If your source code has a
  160.      .BAS or .MAK extension, then the extension is not required.
  161.  
  162.        You can also select the /Q and /L option switches
  163.      explained under "Switches", above.
  164.  
  165.        You can save the current configuration information as your
  166.      "Master" configuration file by selecting the "Save as Master
  167.      CFG" command button on the bottom of the screen.  This command
  168.      button can be selected by moving to the field with the TAB
  169.      button and pressing enter, pressing ALT-M or placing the mouse
  170.      cursor over the command button and pressing the left mouse button.
  171.      A file named PREQDFLT.CFG will be created in the same directory as
  172.      PREQLB.EXE saving the Link and support library information.  If you
  173.      start PreQLB from the command line, it will check for the presence
  174.      of this file and use these values as its default.  If you are using
  175.      the pre-processing commands mentioned above, they are handled in
  176.      the following manner.  '#SupportLib will overwrite any existing
  177.      values with the LAST '#SupportLib value encountered being used. Any
  178.      '#Libraries or '#TrailingObject variables encountered will be
  179.       APPENDED to whatever may exist in the default configuration file.
  180.  
  181.        Whenever PreQLB parses a module(s), it creates a configuration
  182.      file for that program with the name of <SourceFile>.CFG. This
  183.      configuration file will contain all of the information passed to
  184.      the linker in the PREQLB.RSP file, which is a combination of what
  185.      was passed in the default configuration file (if any) and the
  186.      information entered in the dialog box. This allows you to run
  187.      PreQLB from the command line, bypassing the dialog box input and
  188.      speeding up your processing time.
  189.  
  190.        Pressing the enter key or selecting the Build QLB command button
  191.      causes PREQLB to begin processing. It then analyzes your source
  192.      module(s) and builds the Quick library. The program will check
  193.      to make sure it can find the support and LINK libraries in the
  194.      path provided or in the path defined by the LIB environment
  195.      variable. If any library is not be found, an error message will
  196.      appear and you will remain in dialog mode. You will then be prompted
  197.      to provide the correct path or to update your LIB environment variable.
  198.  
  199.        When PreQLB has processed your file(s), it will list on the display
  200.      all of the routines that were DECLAREd in each module but never used,
  201.      and any BASIC procedures in the module(s) that were never used. Since
  202.      this information may scroll off the screen too quickly for you to
  203.      read, PreQLB places this information in a file with the name
  204.      <SourceFile>.EXT in your current directory.
  205.  
  206.      What PREQLB Does
  207.  
  208.        If PREQLB encounters an $INCLUDE statement in a module,
  209.      and the specified file includes a path name, that path will
  210.      be searched for the file. If no path name is included,
  211.      PREQLB will search the current directory for the specified
  212.      file. If the $INCLUDE file is not located, PREQLB will check
  213.      the DOS environment for the presence of the "INCLUDE"
  214.      environment variable. If found, PREQLB can search the
  215.      appropriate directories for $INCLUDE files.
  216.  
  217.        In preparation for building the QLB, PREQLB will create
  218.      two files called PREQLB.RSP and PQ.BAT. The PQ.BAT batch
  219.      file is executed by PREQLB. The batch file invokes the LINK
  220.      program and the response file PREQLB.RSP provides all the
  221.      necessary information required to build the QLB. These files
  222.      are not deleted when the operation is finished unless you select
  223.      those options in the dialog box, so you can use them to rebuild
  224.      the library again, without running PREQLB.
  225.  
  226. VBDOS
  227.      If you are creating a quick library for VBDOS, there are only
  228.      two considerations that you need to be aware of.
  229.      1) You MUST save you forms and subs "As Text".
  230.      2) If you are using custom controls for VBDOS, you will need to
  231.         use the #TrailingObject command to link the object modules
  232.         for the custom control(s) into the QLB.  Since custom controls
  233.         are not declared and referenced like Subs and Functions, PreQLB
  234.         is not aware of their existance.
  235.  
  236.  
  237. PREQLB Speed Tips
  238.  
  239. \     Use the pre-processing commands in your code to
  240.       identify the support library, LINK libraries and any special
  241.       object modules your QLB will need. Then type:
  242.                               
  243.                     PREQLB Filename <Enter>
  244.                               
  245.       PREQLB will obtain all the information it needs
  246.       directly from your source code.
  247.                               
  248.       Using the pre-processing commands also means you will
  249.       have a permanent reference of what libraries and files are
  250.       needed for your program.
  251.  
  252. \    If you have a multi-module program where more than one
  253.      module uses the same $INCLUDE file(s), and the $INCLUDE
  254.      file(s) need only to be processed once, then make sure you
  255.      use the /Q switch. This switch can be passed on the command
  256.      line:
  257.                               
  258.                     "PREQLB <ProgramName> /Q"
  259.                               
  260.      or saved in a .CFG file from the dialog screen. If you
  261.      use this switch and receive an "Unresolved External" error
  262.      message from the linker, run PREQLB again without the /Q
  263.      switch and the Quick library should be created successfully.
  264.  
  265. \    If you are building QLB's for large programs that
  266.      utilize several LINK libraries and you have a RAM disk, copy
  267.      your LINK libraries, source code and PREQLB.EXE to the RAM
  268.      disk and run the program from that drive. The speed increase
  269.      can be very significant. To automate this process, create a
  270.      small batch file that copies the necessary files to the RAM
  271.      disk and optionally starts PREQLB.
  272.  
  273.      If you receive an error message from PreQLB to the effect:
  274.      "Bad filename in module:xxxx", this means that you have a bad
  275.      .CFG file that was created with an earlier version of this program.
  276.      To correct the problem, simply delete all the .CFG files and
  277.      run PreQLB again.
  278.  
  279.